Skip to main content

signercli -cert

Certificate Management Command – Full Reference (Updated)​

1. Overview​

The signercli -cert command provides full lifecycle management of certificates stored on the Signer Server.

It supports:

  • Listing certificates by purpose
  • Distinguishing certificates with or without private keys
  • Inspecting certificate details
  • Selecting an active certificate for signing
  • Uploading certificates to multiple storage backends
  • Downloading certificates in various formats
  • Updating metadata
  • Securely deleting certificates and optionally related private keys

Important

Certificates and private keys are managed as separate objects.

A certificate can exist without an associated private key.

2. Command Usage​

signercli -cert <subcommand> [options]

3. Subcommands​

SubcommandDescription
list [purpose]List certificates by purpose
get <id>Get certificate details
id [cert_id] [label]Get or set the active certificate
pemExport PEM of the active certificate
password <password>Set private key password
upload <file>Upload a certificate
download <id>Download certificate (PEM / DER)
download-pfx <id>Download certificate as PFX
update <id>Update certificate metadata
delete <id>Delete a certificate
helpDisplay help message

4. Certificate Purposes​

Certificates are categorized by purpose, derived from EKU and metadata.

Purpose Values​

PurposeDescription
allCertificates that have an associated private key (default)
anyAll certificates, including those without private keys
codesignCode signing certificates
docsignDocument signing certificates
serverauthSSL/TLS server authentication
clientauthClient authentication
timestampTimestamping certificates
ocspOCSP signing certificates
caCA certificates
encryptEncryption certificates
verifyVerification certificates

Important Distinction​

  • all → filters out certificates without private keys
  • any → shows every certificate, regardless of key linkage

This distinction is critical for:

  • CA inventories
  • Trust store management
  • CSR-based workflows
  • Pre-issued certificates awaiting key linkage

5. Authentication Options​

OptionDescription
-api-key <key>Authenticate using API key (bypasses login)
-host <url>Server URL (required with -api-key)
-profile <name>Use settings from a configuration profile

Authentication rules:

  • API key authentication bypasses interactive login
  • API key permissions define allowed operations
  • API key takes precedence over login tokens

6. Listing Certificates​

List Certificates with Private Keys (Default)​

signercli -cert list -api-key <key> -host https://server:7443

Equivalent to:

signercli -cert list all

List All Certificates (Including Without Private Keys)​

signercli -cert list any -api-key <key> -host https://server:7443

Use cases:

  • CA certificate inventory
  • CSR-issued certificates awaiting linkage
  • Trust-only certificates

List Certificates by Purpose​

signercli -cert list codesign -api-key <key> -host https://server:7443

7. Viewing Certificate Details​

signercli -cert get <certificate_id> -api-key <key>

Displays:

  • Subject / Issuer
  • Serial number
  • Validity period
  • Purpose
  • Storage backend (DB / SW_HSM / HW_HSM)
  • Private key linkage status

8. Active Certificate Management​

Show Active Certificate​

signercli -certid

Set Active Certificate​

signercli -certid <certificate_id> [label]

The active certificate is used by default for:

  • Code signing
  • Document signing
  • Verification operations

9. Export Active Certificate (PEM)​

signercli -cert pem

  • Exports public certificate only
  • Private key is never included

10. Uploading Certificates​

Command Syntax​

signercli -cert upload <file> [options]

Upload Options​

OptionDescription
-name <name>Certificate display name
-desc <description>Certificate description
-storage <type>DB, SW_HSM, HW_HSM (default: DB)
-hsm-slot <id>HSM slot ID (HW_HSM only)
-hsm-pin <pin>HSM PIN (HW_HSM only)

Storage Types​

DB (Default)​

signercli -cert upload cert.pem -name "My Cert"

SW_HSM (Software HSM)​

signercli -cert upload cert.pem -storage SW_HSM

HW_HSM (Hardware HSM)​

signercli -cert upload cert.pem \
  -storage HW_HSM \
  -hsm-slot 0 \
  -hsm-pin 1234

Upload Notes​

  • Uploading a certificate does not upload a private key
  • Private key must already exist in the target backend
  • HSM PINs are never stored

11. Downloading Certificates​

PEM / DER Download​

signercli -cert download <id> -format pem -o /path
signercli -cert download <id> -format der -o /path

Include Certificate Chain​

signercli -cert download <id> -include-chain -o /path

Download as PFX​

signercli -cert download-pfx <id> \
  -password <pwd> \
  -o /path

⚠️ PFX availability depends on:

  • Storage backend
  • Key export policy
  • HSM restrictions

12. Updating Certificate Metadata​

signercli -cert update <id> \
  -name "New Name" \
  -desc "Description"

  • Metadata only
  • Certificate contents are not modified

13. Deleting Certificates​

Delete Certificate Only​

signercli -cert delete <id>

signercli -cert delete <id> -delete-related

Delete HSM-Backed Certificate​

signercli -cert delete <id> -hsm-pin <pin>

⚠️ Deletion is irreversible.

14. Output Formats​

-format classic | json | table | csv

Used for:

  • Automation
  • CI/CD
  • Auditing and reporting

15. Relationship to Other Commands​

CommandDescription
signercli -privkeyPrivate key management
signercli -pubkeyPublic key management
signercli -csrCSR generation
signercli -cert-distAutomated Let’s Encrypt SSL
signercli -codesign-listCode signing shortcut
signercli -codesign-idCode signing shortcut

16. Typical Use Cases​

  • Managing certificates with and without keys
  • CA trust store inventory
  • Secure CI/CD signing
  • HSM-backed production signing
  • Migration from legacy commands

17. Summary​

The signercli -cert command is the authoritative and unified interface for certificate management, providing:

  • Purpose-aware filtering
  • Clear distinction between certificates with and without keys
  • HSM-aware operations
  • Secure automation via API keys
  • Enterprise-grade lifecycle control

It is the recommended command for all certificate-related workflows.